STRUCTURES

Section: Miscellaneous Library Functions (3X)
Updated: August 6, 1990
Index Return to Main Contents

NAME

structures - aggregated data definitions

SYNOPSIS

#include structures.f83

structures

DESCRIPTION

Allows composition of data field description to build structures. A basic language extension library in the tile forth kernel and used throughout the source code library to describe data structures. The "structures" package extends the traditional "record" or "structure" concept and allows initialization and high level management code to be defined together with the structure itself.

: align ( -- ): Used within a structure type field definition section to align the current field address to an even address.
: as ( -- struct.type) immediate: Used in the following form:
as <struct-type-name> ( -- struct.type)
Returns the address of the body of the structure type information. This address may be passed to the structure instance initialization function, "initiate".
: assign ( x y -- ) immediate: Used in the following form:
x y assign <struct-type-name>
or
x y assign <prim-type-name>
Assigns the structure or primitive pointed to by "y" the value of "x". The primitive types are equivalent to the structure type field names, "byte", "word", "long", "ptr" and "enum".
struct.field byte ( -- ): Used in the following form:
byte <field-name> ( addr1 -- addr2)
within a structure type definition section to create an access field name to a byte.
: bytes ( n -- ): Used in the following form:
<number> bytes <field-name> ( addr1 -- addr2)
within a structure type definition section to create a field access name to a given <number> of bytes.
struct.field enum ( -- ): Used in the following form:
enum <field-name> ( addr1 -- addr2)
within a structure type definition section to create a field access name to an enumerate. The size of an enumerate field is four bytes.
: initiate ( addr struct.type -- ): Used in the following form:
<instance> as <struct-type-name> initiate
Take a pointer to a memory area and initializes it according to the initialization code for the structure type given as the second parameter. Parameters to this code section can be passed as usual on the parameter stack.
struct.field long ( -- ): Used in the following form:
long <field-name> ( addr1 -- addr2)
within a structure type definition section to create a field access name to a long number. The size of a long is four bytes.
: new-struct ( -- addr) immediate: Used in the following form:
new-struct <struct-type-name> ( -- addr)
to allocate and initialize an instance of a structure type. A pointer to the instance is returned. The instance is not bound to any variable.
: not-equal ( x y -- bool) immediate: Used in the following form:
x y not-equal <struct-type-name>
or
x y not-equal <prim-type-name>
to compare two structure instances. The primitive types are equivalent to the structure type field names, "byte", "word", "long", "ptr" and "enum".
struct.field ptr ( -- ): Used in the following form:
ptr <field-name> ( addr1 -- addr2)
within a structure type definition section to create a field access name to a pointer. The size of a pointer is four bytes.
: sizeof ( -- num) immediate: Used in the following forms:
sizeof <struct-type-name>
or

sizeof <prim-type-name>
Returns the size, in bytes, of a structure or primitive type. The primitive types are "byte", "word", "long", "ptr" and "enum".
: struct ( -- ): Used in the following form:
struct <struct-type-name> <field-name> ( addr1 -- addr2)
within a structure type definition section to create a field access name to a structure. The structure is not initialized automatically by the structure type. This should be performed by the initialization code of the structure type it is a part of. This may be performed with the words "as" and "initiate". Remember to pass necessary parameters to the initialization code.
: struct.does ( addr -- ) immediate compilation: Used within a structure type definition section to define the end of the structure layout or initialization code and the beginning of the instance action code. At run-time, performed for entry bounded (named) instance, the code receives a pointer to the instance as parameter.
: struct.end ( -- ) immediate: Used to terminate a structure type definition.
: struct.init ( addr -- ): Used within a structure type definition section to terminate the structure layout and the beginning the definition of the initialization
code section. At run-time the code receives a pointer to the instance as a parameter.
: struct.type ( -- ): Used in the following forms:
struct.type <struct-type-name> ( ... -- )
<struct-type-layout>
struct.init ( ... addr -- ...)
<initialization-part>
struct.does ( ... addr -- ...)
<instance-part>
struct.end
and then:
<struct-type-name> <instance-name>
Starts the definition of a structure type. The layout section <struct-type-layout> may contain the words; <n> bytes <field-name>, allocates "n" bytes, byte <field-name>, a byte, word <field-name>, a word, long <field-name>, a long, ptr <field-name>, a pointer, enum <field-name>, an enumerative, and struct <struct-type-name> <field-name>, a structure. To align a field to even address use "align". The initialization code receives a pointer to the block to initialize and any additional parameters. Thus additional memory may be allocated directly after the block. If the structure contains structure fields these should be initialized by the initialization code. For this "as" and "initiate" are used; <instance> as <struct-type-name> initiate. The normal action performed by a instance of a structure type is to return the address to the instance. The optional "struct.does" part redefines the normal action of a created structure block. It receives a pointer to the instance as parameter and any additional parameters. The sections "struct.init" and "struct.does" are optional.
vocabulary structures ( -- ): Vocabulary for structure type extensions. Include into the vocabulary search structure, "context", to allow use of structures and description of aggregated data structures.
: this ( -- addr): Returns the compilation address of the latest defined word.
struct.field word ( -- ): Used in the following form:
word <field-name> ( addr1 -- addr2)
within a structure type definition to create a field access name to a word. The size of a word is two bytes.

INTERNALS

Private definitions in the structures vocabulary;

field +size ( struct.type -- addr) private: Field for accessing the size of a structure type. This field is a long containing the number of bytes to allocate for an instance of the structure type.
field +initiate ( struct.type -- addr) private: Field for accessing the initialization code of a structure type. This field is a "ptr" containing a pointer to the initialization code for the structure type. A zero value, "nil", indicates that the structure type does not perform initialization.
: struct.field ( bytes -- ) private: Used in the following form:
<bytes> struct.field <field-type-name>
to create additional field types other than "byte" etc.
: make-struct ( struct.type -- addr) private: Given a pointer to a structure type information block, as generated by "as", allocates memory in the dictionary and initializes it. Returns a pointer to the created instance.

EXAMPLES

An example showing how to defined a list structure:

struct.type LIST ( -- )
        ptr +next ( list -- addr)
struct.init ( list -- )
        nil swap +next !
struct.end

sizeof LIST . 
new-struct LIST constant x

LIST y

NOTE

The function list is sorted in ASCII order. The type and mode of
the entries are indicated together with their parameter stack effect.

The "structures" library optimizes the first field so that access becomes an immediate word with no effect. The most common accessed field should be placed first in a "structure" definition.

COPYING

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR

Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se

This document was created by man2html, using the manual pages.
Time: 17:37:50 GMT, February 06, 2023